home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / util / libs / ControlPad.lha / controlpad.doc < prev    next >
Encoding:
Text File  |  1995-03-26  |  12.4 KB  |  320 lines
  1. ControlPad Library Version 40.2
  2. Copyright ©1995 by Randall Richards and Joseph Carlson.
  3. March 26, 1995
  4.  
  5. The 'ControlPad.Library' and all files in this archive are Copyright ©1995
  6. by Joseph Carlson and Randall Richards, but are freely distributable as a
  7. whole archive if left unmodified.  The file 'ControlPad.library' may be
  8. included with freely distributable games if we are notified by email AND
  9. credit is given to Joseph Carlson and Randall Richards.  (Just using the
  10. function cpShowLogo() qualifies as credit.)
  11.  
  12.  
  13. Requirements:  Any Amiga with AmigaDOS 2.0 or higher.
  14.  
  15. Recommended:   CP-1 ControlPad Adapter required for accessing all of
  16.                the buttons on a Sega ControlPad.
  17.  
  18. Installation:  Copy 'ControlPad.Library' to your LIBS: directory.
  19.  
  20.                Programmers should copy 'ControlPad.h' to the appropriate
  21.                includes directory (for SAS/C this is 'include:libraries'.)
  22.  
  23. Description:   This library allows programmers to effortlessly include
  24.                support for joysticks and Sega Genesis(TM) compatible
  25.                ControlPads (including the extra buttons that can't be found
  26.                on conventional joysticks for the Amiga.)
  27.  
  28.  
  29. Files included in this archive:
  30.  
  31.    controlpad.doc       - what you're reading...
  32.    controlpad.h         - an include file for use with your own code.
  33.    controlpad.library   - the library itself.
  34.  
  35.    cp-1.doc             - info on the CP-1 adapter.
  36.  
  37.    cpTest               - a program for testing ControlPads and Adapters
  38.    cpTest.doc           - docs for cpTest.
  39.    cpTest.lbm           - picture file used by cpTest.
  40.  
  41.    cp_example           - an ugly example program.
  42.    cp_example.c         - source for example showing how easy it is to use
  43.                           the library.
  44.  
  45.  
  46. -- Introduction -----------------------
  47.  
  48.    This library allows programs to read Sega Genesis(TM) type ControlPads
  49. that are plugged into the Amiga via the CP-1 ControlPad Adapter.  Standard
  50. joysticks are also supported with or without the adapter.
  51.  
  52. Library functions include the ability to allocate and read either or both game
  53. ports on the Amiga, disable the mouse, test for adapters, check for controller
  54. type, as well as a nice title graphics that fade in and out (AGA/ECS aware).
  55. All this in a little 14k library (which includes the graphics data).
  56.  
  57. Further information on the CP-1 ControlPad Adapter is in the file 'CP-1.doc'.
  58.  
  59.  
  60.  
  61. -- Library Functions ------------------
  62.  
  63. The library functions contain references of the following:
  64.  
  65. 'CPHANDLE' is a type definition (typedef void * CPHANDLE).  It is a handle
  66.    used by the library to keep track of what program has what allocated.
  67.  
  68. 'unit' contains flags for defining what ports are being used.  See the
  69.    'CPU_...' defines described in 'controlpad.h'.
  70.  
  71. The function cpGet() returns a bit-packed UWORD which fully describes the
  72. condition of the port.  See the 'CPF_...' defines in the h file for the
  73. meaning of all 16 bits.
  74.  
  75.  
  76. Here are the library functions:
  77.  
  78.    CPHANDLE cpAlloc(UBYTE unit);
  79.       Purpose:  Allocates one or both ports for use.
  80.  
  81.       Needs:    unit - must be one of the following: CPU_MOUSEPORT,
  82.                       CPU_JOYPORT, or CPU_BOTHPORTS.
  83.  
  84.       Returns:  a CPHANDLE pointer if successful, or NULL if allocation
  85.                 failed.
  86.  
  87.       Comments: If 'unit' includes the mouseport, then the gameport.device
  88.                 Vertical Blank Routine is temporarily removed (This disables
  89.                 polling of the the mouse.)
  90.  
  91.  
  92.  
  93.    void cpFree(CPHANDLE cph);
  94.       Purpose:  Frees memory associated with the handle.  Re-installs the
  95.                 "gameport.device" vertical blank interrupt if the mouseport
  96.                 is no longer being used by the library.
  97.  
  98.       Needs:    cph - the CPHANDLE allocated with cpAlloc() or cpReAlloc().
  99.  
  100.       Comments: cph is now invalid and can no longer be used by any function
  101.                 (Bad things will happen if you try...).
  102.  
  103.  
  104.    UWORD cpGet(CPHANDLE cph, UBYTE unit);
  105.       Purpose:  Reads the ControlPad in the specified port(s).
  106.  
  107.       Needs:    cph - an allocated CPHANDLE.
  108.                 unit - the port to read.
  109.  
  110.       Returns:  a packed UWORD with 16 bits of information about 'unit'.
  111.                 Bits include direction, all buttons, type of controller,
  112.                 etc.  See below and CPB_xxx defines in 'controlpad.h'.
  113.  
  114.       Comments: This function does not queue up events in any way.
  115.                 It only returns real-time information.  If CPU_BOTHPORTS
  116.                 is specified, result is both ControlPads OR'd together
  117.                 (useful for waiting for the START button on either
  118.                 controller).
  119.  
  120.       The combination of CPF_UP, CPF_DOWN, CPF_LEFT, and CPF_RIGHT bits
  121.       bits that are set (1) indicate current direction being pressed on
  122.       the joystick or controlpad.
  123.  
  124.       The CPF_A, CPF_B, CPF_C, and CPF_START bits that are set (1) indicate
  125.       the buttons that are currently being pressed on the controlpad.  If a
  126.       joystick is being used, CPF_B returns the joystick fire button.
  127.  
  128.       When set, the CPF_3BUTTON bit indicates the presence of a controlpad.
  129.       When clear (0), this bit indicates a joystick or other controller is
  130.       attached.
  131.  
  132.       CPF_INUSE indicates wether the port has been allocated (1) or not (0).
  133.       CPF_ERROR indicates the library detected an error when reading the port.
  134.       The error could mean there is a mouse plugged in or a hardware problem.
  135.  
  136.       The bits returned by cpGet() should only be considered valid if CPF_INUSE
  137.       is set and CPF_ERROR is clear.
  138.  
  139.       The CPF_X,_Y,_Z, and _MODE may be supported in future versions if I can
  140.       figure out how to read those buttons.  (Please contact me if you have
  141.       any information on how they are read in...)
  142.  
  143.  
  144.  
  145.    CPHANDLE cpReAlloc(CPHANDLE cph, UBYTE unit);
  146.       Purpose:  This is used when you want to change what units are allocated by
  147.                 the handle.  This function actually calls cpFree() followed by a
  148.                 cpAllocate().
  149.  
  150.       Needs:    cph - the CPHANDLE allocated with cpAlloc() or cpReAlloc().
  151.                 unit - the new port(s) to be allocated for use.
  152.  
  153.       Returns:  A new CPHANDLE with the specified ports allocated or
  154.                 NULL if allocation failed.
  155.  
  156.       Comments: 'cph' is now invalid and should not be freed.  The returned
  157.                 CPHANDLE should be used for further function calls and must
  158.                 be freed before program termination.  A suggested use is:
  159.                    cph = cpRealloc(cph, unit);
  160.                 This redefines cph so it is valid again and avoids need for
  161.                 extra variables.
  162.  
  163.  
  164.    UBYTE cpLock(CPHANDLE cph, UBYTE unit);
  165.       Purpose:  To lock a port from being allocated by another program.
  166.  
  167.       Needs:    cph - a valid CPHANDLE.
  168.                 unit - the unit to lock (must not be in use by any program)
  169.  
  170.       Returns:  the 'unit' successfully locked.  See CPU_xxx defines.
  171.  
  172.       Comments: Really only useful for keeping other programs that use this
  173.                 library from disabling the mouse.
  174.  
  175.  
  176.  
  177.    UBYTE cpUnLock(CPHANDLE cph, UBYTE unit);
  178.       Purpose:  To unlock a port that was locked with cpLock().
  179.  
  180.       Needs:    cph - the CPHANDLE used to lock the port.
  181.                 unit - the unit to unlock.
  182.  
  183.       Returns:  the 'unit' successfully unlocked.  See CPU_xxx defines.
  184.  
  185.  
  186.  
  187.    UBYTE cpUnit(CPHANDLE cph);
  188.       Purpose:  Tells you what ports are allocated by the CPHANDLE.
  189.  
  190.       Needs:    cph - an allocated CPHANDLE.
  191.  
  192.       Returns:  the 'unit' currently allocated by cph.  See CPU_xxx defines
  193.                 in 'controlpad.h'
  194.  
  195.  
  196.  
  197.    UBYTE cpTest();
  198.       Purpose:   To test for CP-1 ControlPad Adapters.
  199.  
  200.       Returns:   the 'unit's that currently have a ControlPad Adapter
  201.                  installed.
  202.  
  203.       Comments:  This does not test what type of controller is in the port.
  204.                  cpGet() will tell you controller type.  This is useful if
  205.                  you want a 'CP-1 Adapter Detected' type message.
  206.  
  207.  
  208.    void cpShowLogo(int time);
  209.       Purpose:   Fades in and out a nice hires logo stating 'CP-1 ControlPad
  210.                  Adapter supported' message.
  211.  
  212.       Needs:     time - the number of ticks (50 or 60ths of a second) to keep
  213.                     the logo on screen between fade in and fade out.  A value
  214.                     of at least 120 is recommended.
  215.  
  216.       Comments:  The current View is saved before the controlpad logo screen
  217.                  is displayed, and restored upon completion.  This means you
  218.                  can open your own screen with Intuition or your own custom
  219.                  View (system unfriendly way) and it will still be put back
  220.                  up in front for you when the function completes.
  221.  
  222.                  This display even utilizes an AGA mode (with Intuition) if
  223.                  available!
  224.  
  225.                  Please, please, please show this off in your programs!
  226.  
  227.  
  228.  
  229. -- Sample Code ------------------------
  230.  
  231. The file 'cp_example.c' shows an example of how to incorporate this library
  232. into your own code.  To also help, here is some more sample code:
  233.  
  234.  
  235.    #include <libraries/controlpad.h>   // Contains all defines and function pragmas
  236.  
  237.    void piece_of_code () {
  238.       struct Library *ControlPadBase;  // Must be 'ControlPadBase'
  239.       CPHANDLE cph = NULL;
  240.       UWORD cpad, cpad2;
  241.       int x, y;
  242.                                        // Try to Open the Library...
  243.       if (ControlPadBase = OpenLibrary(ControlPadName, 0))
  244.       {                                // Display fancy logo screen...
  245.          cpShowLogo(120);
  246.                                        // Allocate both ports...
  247.          if (cph = cpAlloc(CPU_BOTHPORTS))
  248.          {
  249.             do                         // Wait for either Start button...
  250.             {
  251.                WaitTOF();
  252.                cpad = cpGet(cph, CPU_BOTHPORTS);
  253.             } while (!(cpad & CPF_START));
  254.  
  255.             do                         // get both ports separately and
  256.             {                          // do something with them...
  257.  
  258.                cpad = cpGet(cph, CPU_MOUSEPORT);
  259.                cpad2 = cpGet(cph, CPU_JOYPORT);
  260.                done = doSomething(cpad, cpad2);
  261.                                        // loop until done or 'A' button is
  262.                                        // pressed on joyport controlpad...
  263.             } while (!done || !(cpad2 & CPF_A));
  264.  
  265.                                        // free only the mouseport and
  266.                                        // save our new cpHandle...
  267.             if (cph = cpReAlloc(cph, CPU_JOYPORT))
  268.             {
  269.                                        // Lock the mouseport...
  270.                if (cpLock(cph, CPU_MOUSEPORT) != CPU_MOUSEPORT)
  271.                   printf("cpLock() failed!\n");
  272.  
  273.                do                      // get just joyport controlpad info
  274.                {                       // and work with it...
  275.                   cpad = cpGet(cph, CPU_JOYPORT);
  276.                                        // calculate delta x and y from cpad.
  277.                   x = ((cpad & CPF_RIGHT) != 0) - ((cpad & CPF_LEFT) != 0);
  278.                   y = ((cpad & CPF_DOWN) != 0) - ((cpad & CPF_UP) != 0);
  279.                   done = doSomethingElse1(x, y);
  280.                } while (!done);
  281.  
  282.                                        // UnLock the mouseport...
  283.                if (cpUnLock(cph, CPU_MOUSEPORT) != CPU_MOUSEPORT)
  284.                   printf("cpUnLock() failed!\n");
  285.  
  286.             } else
  287.                printf("cpReAlloc() failed.\n");
  288.  
  289.                                        // Free our handle...
  290.             cpFree(cph);
  291.  
  292.          } else
  293.             printf("cpAlloc() failed.\n");
  294.  
  295.                                        // Close Library...
  296.          CloseLibrary(ControlPadBase);
  297.       } else
  298.          printf("Could not open controlpad.library!\n);
  299.    }
  300.  
  301. -----
  302.  
  303. 'Sega' and 'Genesis' are trademarks of SEGA.
  304.  
  305.  
  306. == REVISION HISTORY ===========================================================
  307.  
  308. Version 40.2
  309.    ·  Fixed a pair of Enforcer hits that occured whenever the library was
  310.          opened.  Thanks go to David Ferguson for reporting this one.
  311.    ·  Revision number reported incorrect in the Initial release.  This one is
  312.          a bit embarassing.  I though the version command wasn't working
  313.          because it would always return '40.0' no matter what the rev number
  314.          was set to.  Turns out version returns the correct number AFTER the
  315.          library has been loaded, not before...  Anyway, 40.1 reports itself
  316.          as 40.666! Please delete the old version and forget it ever existed.
  317.  
  318. Version 1.0 (aka 40.666)
  319.    ·  Initial release.
  320.